home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / Developer Kits / Arrange Developer Kit / Interfaces / Module.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-07-15  |  11.4 KB  |  324 lines  |  [TEXT/MPS ]
  1. #ifndef MODULE_H
  2. #define MODULE_H
  3.  
  4. /* This flag controls application code used to help debug plugin modules,
  5.  * as well as debugging code within a module itself.
  6.  */
  7. #ifndef ModuleDebug
  8. #define ModuleDebug 1
  9. #endif
  10.  
  11.  
  12. #ifndef MODULE_R_H
  13. #include "Module.r.h"
  14. #endif
  15.  
  16. #ifndef CKIDEFS_H
  17. #include "ModuleSupport.h"
  18. #endif
  19.  
  20.  
  21. /* This is the common include file for both Plug-in modules and an application
  22.  * which makes use of them.  It defines the data structures which are visible
  23.  * to a module.  This file contains only application-independent data
  24.  * structures; data structures specific to a particular application must be
  25.  * defined elsewhere.
  26.  */
  27.  
  28.  
  29. /* When a module is first loaded, we assign it a ModuleID which is then used
  30.  * to refer to that module as long as it remains loaded.  This is simply an
  31.  * index into a table of loaded modules.  Legal values are always positive;
  32.  * zero or negative ModuleIDs indicate nil or error conditions.  When a
  33.  * module is unloaded, its ModuleID can be reused.
  34.  * 
  35.  * Note that this is _not_ the module's permanent unique ID (the 32-bit value
  36.  * stored in the module's 'MDdf' resource).  It is a 16-bit tag used to refer
  37.  * to a loaded module during a particular session of Arrange.
  38.  */
  39. typedef Short ModuleID;
  40.  
  41.  
  42. struct ModuleParamBlock;
  43. typedef struct ModuleParamBlock ModuleParamBlock;
  44.  
  45.  
  46. /* The following declarations are required to allow modules to be compiled
  47.  * using Think C, which has different parameter-passing conventions than
  48.  * MPW C: namely, parameters are pushed in the opposite order (left-to-right
  49.  * instead of right-to-left), 2-byte parameters are not expanded to 4 bytes,
  50.  * and the callee is responsible for removing the parameters from the stack.
  51.  * 
  52.  * By appending ", ..." to the end of each parameter list, we force Think C
  53.  * to use the MPW-style calling conventions (except for the expansion of
  54.  * 2-byte values to 4 bytes).  This is done using the ENDP macro, which
  55.  * expands to the empty string except when compiling under Think C.  To
  56.  * force 2-byte values to be expanded to 4 bytes, we define aliases for
  57.  * ModuleID, Boolean, and Short to be used in parameter declarations.
  58.  */
  59. #ifdef __SC__
  60.     #define ENDP , ...
  61.     typedef long pModuleID;
  62.     typedef long pBoolean;
  63.     typedef long pShort;
  64. #else // ndef __SC__
  65.     #define ENDP
  66.     typedef ModuleID pModuleID;
  67.     typedef Boolean  pBoolean;
  68.     typedef Short    pShort;
  69. #endif // else ndef __SC__
  70.  
  71.  
  72. /* Struct defining the QuickDraw global variables - used as a field in
  73.  * ModuleSysInfo (below).
  74.  */
  75. #if !UniversalIncludes
  76. struct QDGlobals
  77.     {
  78.     char privates[76];
  79.     long randSeed;
  80.     BitMap screenBits;
  81.     Cursor arrow;
  82.     Pattern dkGray;
  83.     Pattern ltGray;
  84.     Pattern gray;
  85.     Pattern black;
  86.     Pattern white;
  87.     GrafPtr thePort;
  88.     }; // QDGlobals
  89. #endif // if !UniversalIncludes
  90.  
  91.  
  92. // This struct contains info about a currently loaded Plugin module.
  93. struct ModuleInfo
  94.     {
  95.     Short    vers;           // Version number for this record (currently 1).
  96.     FSSpec   file;       // File containing the module.
  97.     Short    fileRef;    // Refnum for file's resource fork.
  98.     Short    defID;       // ID of the module definition resource.
  99.     ModuleID    modID;       // ModuleID assigned when this module was loaded.
  100.     const void* appInfo; // Application-specific info (nil if unused).
  101.     
  102.     // Information copied from the ModuleDef record.
  103.     uShort flags;            // ModuleFlags values (set unused bits to zero).
  104.     char name[32];          // Unique name (0-terminated) for this module.
  105.     uInteger id;         // Unique ID (registered with CKI) for this module.
  106.     uInteger modVers;    // Module version.
  107.     Short rootCodeID;    // ID of the root code resource ('MDcd') for this module
  108.                                // (code resource containing the module's boot function);
  109.                                // value is relative to the ID of the 'MDdf' resource.
  110.                                // -1 if module has no boot function.
  111.     }; // ModuleInfo
  112.  
  113.  
  114. // This struct specifies an entry point within a loaded module.
  115. struct ModuleEntryPoint
  116.     {
  117.     ModuleID module; // ID of the module owning this entry point; 0 indicates
  118.                           // a "nil" value.
  119.     Short    rsrcID; // ID of the resource ('MDcd') containing the entry point.
  120.     uInteger offset; // Entry point offset within the code resource.
  121.     
  122.     Boolean IsNil()  { return module == 0; }
  123.     Boolean NotNil() { return module != 0; }
  124.     
  125.     Boolean operator==(const ModuleEntryPoint &entry) const;
  126.     Boolean operator!=(const ModuleEntryPoint &entry) const { return !operator==(entry); }
  127.     }; // ModuleEntryPoint
  128.  
  129.  
  130. // This struct provides information about the machine on which we are running.
  131. struct ModuleSysInfo
  132.     {
  133.     Short   vers;            // Version number for this record (currently 2).
  134.     Short   pad;            // Unused (always 0).
  135.     Integer sysVers;        // System software version number.
  136.     Boolean hasFPU;        // True if a floating-point coprocessor is present.
  137.     Boolean hasColorQD;    // True if Color QuickDraw is available.
  138.     Rect      screenBounds;// Bounds of the monitor containing the menu bar.
  139.     FSSpec  sysFolder;    // Location of the system folder.
  140.     FSSpec  prefsFolder;    // Location of the application's preferences folder,
  141.                                 // or the system folder if the app doesn't create
  142.                                 // a custom prefs folder.
  143.     
  144.     // Fields added in version 2 of ModuleSysInfo record:
  145.     
  146.     QDGlobals *qd;            // pointer to QuickDraw globals
  147.     }; // ModuleSysInfo
  148.  
  149.  
  150. /* This enum describes a particular build of the application in which a module
  151.  * is running.  It is used for the "flags" field of a ModuleAppInfo record.
  152.  */
  153. enum MAppFlags
  154.     {
  155.     afInternalDebug = 1,        // Application was compiled with internal debugging
  156.                                     // code enabled.
  157.     afModuleDebug     = 2,        // Application was compiled with module-debugging
  158.                                     // code enabled.
  159.     afDemoVersion     = 4        // This is a demo version of the application (freely
  160.                                     // distributable, some features disabled).
  161.     }; // MAppFlags
  162.  
  163.  
  164. /* This struct provides information about the application inside which a
  165.  * module has been loaded.
  166.  */
  167. struct ModuleAppInfo
  168.     {
  169.     Short     vers;            // Version number for this record (currently 1).
  170.     Short        pad;                // Unused (always 0).
  171.     uInteger  appID;            // Unique identifier for this application.
  172.     uInteger  appVers;        // Application version number.
  173.     FSSpec    appFile;        // Location of the application file.
  174.     Short         appRefnum;        // Refnum for the application's resource fork.
  175.     MAppFlags flags;            // Flags
  176.     }; // ModuleAppInfo
  177.  
  178.  
  179. /* This struct lists the callback functions available for manipulating
  180.  * modules themselves.
  181.  */
  182. struct ModMgrCalls
  183.     {
  184.     Short vers;    // Version number for this record (currently 1).
  185.     Short pad;    // Unused (always 0).
  186.     
  187.     ModuleID                (*FindModuleName)        (const char* name, uInteger minVers ENDP);
  188.     ModuleID                (*FindModuleID)        (uInteger id,      uInteger minVers ENDP);
  189.     const ModuleInfo* (*GetModInfo)            (pModuleID module ENDP);
  190.     OSErr                    (*OpenModFile)            (const FSSpec *file, pShort fileRefnum ENDP);
  191.     
  192.     ModuleEntryPoint  (*GetModuleEntry)        (pModuleID module, uInteger entryID ENDP);
  193.     ProcPtr                (*ModuleCallPrelude)    ( const ModuleEntryPoint *entry,
  194.                                                           OUT ModuleParamBlock *pb ENDP );
  195.     void                    (*ModuleCallEpilogue)( const ModuleEntryPoint *entry,
  196.                                                           const ModuleParamBlock *pb ENDP );
  197.     }; // ModMgrCalls
  198.  
  199.  
  200. // This enum defines some parameters for functions in the MemCalls table.
  201. enum AllocMode { amFreeStore,                  // Allocate on the C++ free store.
  202.                       amPtr,                          // Allocate a Memory Manager pointer.
  203.                       amHdl,                          // Allocate a Memory Manager handle.
  204.                       amTypeMask   = 0xFF,      // Mask for previous options.
  205.                       amFriendly   = 0x100,      // Modifier to disallow allocations
  206.                                                         // which would put us near to running
  207.                                                       // out of memory.
  208.                       amClear      = 0x200,      // Modifier to initialize storage to 0s.
  209.                       amErrIfNoMem = 0x400 }; // Modifier to signal a fatal error,
  210.                                                         // rather than returning nil, if
  211.                                                       // allocation fails.
  212.  
  213. #ifdef __SC__
  214.     typedef long pAllocMode;
  215. #else // ndef __SC__
  216.     typedef AllocMode pAllocMode;
  217. #endif // else ndef __SC__
  218.  
  219.  
  220. /* This struct lists the callback functions available for memory allocation
  221.  * and management.
  222.  */
  223. struct MemCalls
  224.     {
  225.     Short vers;    // Version number for this record (currently 1).
  226.     Short pad;    // Unused (always 0).
  227.     
  228.     void*        (*AllocMem)            (uInteger size, pAllocMode mode ENDP);
  229.     void        (*DeallocMem)        (void* block,     pAllocMode mode ENDP);
  230.     uInteger (*MemAvailable)    ();
  231.     }; // MemCalls
  232.  
  233.  
  234. // This struct lists various utility callback functions.
  235. struct UtilCalls
  236.     {
  237.     Short vers;    // Version number for this record (currently 1).
  238.     Short pad;    // Unused (always 0).
  239.     
  240.     const char* (*GetRString)    (pShort rsrcID, pShort stringIndex ENDP);
  241.     void            (*LowerString) (IO char* string, Integer length ENDP);
  242.     }; // UtilCalls
  243.  
  244.  
  245. /* This struct lists the callback functions available for reporting error
  246.  * conditions.
  247.  */
  248. struct ErrorCalls
  249.     {
  250.     Short vers;    // Version number for this record (currently 1).
  251.     Short pad;    // Unused (always 0).
  252.     }; // ErrorCalls
  253.  
  254.  
  255. /* This struct lists the callback functions available for debugging purposes.
  256.  * These functions are only available if the application has been compiled for
  257.  * module debugging.
  258.  */
  259. struct DebugCalls
  260.     {
  261.     Short vers;    // Version number for this record (currently 1).
  262.     Short pad;    // Unused (always 0).
  263.     
  264.     void (*PrintToLog) (const char* message ENDP);
  265.     }; // DebugCalls
  266.  
  267.  
  268. /* This struct contains a set of function pointers into the application code
  269.  * which can be called from a plugin module.
  270.  */
  271. struct CallbackTbl
  272.     {
  273.     Short vers;                        // Version number for this record (currently 1).
  274.     Short pad;                        // Unused (always 0).
  275.             ModMgrCalls* modMgr; // Module Manager functions.
  276.             MemCalls*     mem;        // Memory allocation/deallocation functions.
  277.             UtilCalls*   util;    // Utility functions
  278.             ErrorCalls*  err;        // Error-logging functions.
  279.             DebugCalls*  dbg;        // Debugging functions; nil in non-debug builds.
  280.     const void*        extra1; // Unused (always nil).
  281.     const void*        extra2; // Unused (always nil).
  282.     const void*        extra3; // Unused (always nil).
  283.     }; // CallbackTbl
  284.  
  285.  
  286. /* This struct defines the parameter block which is passed as the first
  287.  * parameter to all module entry points.  An entry point may have additional
  288.  * parameters, depending on the specific function being called.
  289.  */
  290. struct ModuleParamBlock
  291.     {
  292.     Short vers;                         // Version number for this record (currently 1).
  293.     Short pad;                          // Unused (currently 0).
  294.     uInteger moduleRefcon;          // Module refcon value.
  295.     uInteger hookRefcon;             // Hook-specific refcon value.
  296.     const ModuleSysInfo* sys;    // Pointer to information about this machine.
  297.     const ModuleAppInfo* app;    // Pointer to information about the application.
  298.     const ModuleInfo*    mod;    // Pointer to information about this module.
  299.     const CallbackTbl*   calls;  // Pointer to table of callback functions.
  300.     const void*          extra1; // Unused (always nil).
  301.     const void*                extra2; // Unused (always nil);
  302.     const void*                extra3; // Unused (always nil);
  303.     }; // ModuleParamBlock
  304.  
  305.  
  306. // Values for the action parameter of a module's root entry routine.
  307. enum ModuleRootAction
  308.     {
  309.     mrLoad,        // Module is being loaded - return 1 if module initializes
  310.                     // successfully, 0 otherwise.
  311.     mrUnload,    // Module is being unloaded.  Function result is ignored.
  312.     mrFindEntry // Request for address of a specific entry point in the
  313.                     // module.  Return a ProcPtr, or nil if entry point isn't
  314.                     // available.
  315.     };
  316.  
  317. /* Prototype for a module's root entry point (the function at the beginning
  318.  * of the root code resource).
  319.  */
  320. Integer ModuleRoot(ModuleParamBlock *pb, ModuleRootAction action, Integer p1 ENDP);
  321.  
  322. typedef Integer (*ModuleRootProc)(ModuleParamBlock*, ModuleRootAction, Integer ENDP);
  323.  
  324. #endif // #ifndef MODULE_H